home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / doc / apport / package-hooks.txt < prev    next >
Encoding:
Text File  |  2009-04-06  |  2.8 KB  |  91 lines

  1. Apport per-package hooks
  2. ========================
  3.  
  4. Packages can add additional fields (or even modify existing fields, if
  5. they want) of Apport crash or bug reports by placing a Python code
  6. snippet into
  7.  
  8.   /usr/share/apport/package-hooks/<packagename>.py
  9.  
  10. or
  11.  
  12.   /usr/share/apport/package-hooks/source_<sourcepackagename>.py
  13.  
  14. Apport will import this and call a function
  15.  
  16.   add_info(report)
  17.  
  18. and pass the currently processed problem report. This is an instance
  19. of apport.Report, and should mainly be used as a dictionary. Please
  20. see the Python help of this class for details:
  21.  
  22.   >>> import apport
  23.   >>> help(apport.Report)
  24.  
  25. Package independent hooks
  26. =========================
  27.  
  28. Similarly to per-package hooks, you can also have additional
  29. information collected for any crash or bug. For example, you might
  30. want to include violation logs from SELinux or AppArmor for every
  31. crash. The interface and file format is identical to the per-package
  32. hooks, except that they need to be put into
  33.  
  34.   /usr/share/apport/general-hooks/<hookname>.py
  35.  
  36. The <hookname> can be arbitrary and should describe the functionality.
  37.  
  38. Customize the crash DB to use
  39. =============================
  40.  
  41. To use another crash database than the default one, you should create
  42. an hook that adds a 'CrashDB' field with the name of the database to
  43. use. See /etc/apport/crashdb.conf and
  44. /etc/apport/crashdb.conf.d/*.conf for available databases.
  45.  
  46. Examples
  47. ========
  48.  
  49. Trivial example: To attach a log file /var/log/foo.log for crashes in
  50. binary package foo, put this into /usr/share/apport/package-hooks/foo.py:
  51.  
  52. ------------ 8< ----------------
  53. import os.path
  54.  
  55. def add_info(report):
  56.     if os.path.exists('/var/log/foo.log'):
  57.         report['FooLog'] = open('/var/log/foo.log').read()
  58. ------------ 8< ----------------
  59.  
  60. Apport itself ships a source package hook, see
  61. /usr/share/apport/package-hooks/source_apport.py.
  62.  
  63. An interesting use case of hooks is to detect situations which should
  64. not be reported as bugs, because they happen on known-bad hardware,
  65. from a third-party repository, or other situations. This can be
  66. achieved by adding a field
  67.  
  68.   report['UnreportableReason'] = _('explanation')
  69.  
  70. Such reports are displayed by the apport frontends as
  71. unsupportable/unreportable with the given explanation. Please ensure
  72. proper i18n for the texts.
  73.  
  74. If you want to entirely ignore a crash without presenting an
  75. explanatory error dialog box, use "Ignore" instead of
  76. "UnreportableReason":
  77.  
  78.   report['Ignore'] = 'True'
  79.  
  80. (the actual value does not matter, it just must be a string).
  81.  
  82. If you write hooks, please have a look at the apport.hookutils
  83. module first: 
  84.  
  85.  python -c 'import apport.hookutils; help(apport.hookutils)'
  86.  
  87. It provides readymade and safe functions many standard situations, 
  88. such as getting a command's output, attaching a file's contents, 
  89. attaching hardware related information, etc.
  90.  
  91.